Statement: format
The format statement is used to control the conversion of text to date (the Julian Day Number) and visa versa. It is both a statement and a grammar sub-statement. When used as a statement, it is possible to add to, or replace, a format in an existing grammar.
| format Statement | ||
|---|---|---|
| Format | Example | Output |
| format gcode:fcode { format-statements } | format j:OBLIQUE { separators "/"; inout "{day}/|{month}/|{year}"; } writeln text.g:OBLIQUE 2460136; writeln date.j:OBLIQUE "27/6/2023"; | 10/7/2023 2460136 |
| format gcode:fcode format-string; | format g:UPPER "{day} |{month:m:a:u} |{year}"; writeln text.g:UPPER 2460141; | 15 JUL 2023 |
| grammar gcode { grammar-statements format fcode { format-statements } } | grammar XG { inherit g; format dXmy { output "{Day} |{Month::rn} |{Year}"; } } scheme XS{ base gregorian; grammar XG; } writeln text.XS:dXmy 2460141; | 15 VII 2023 |
| grammar gcode { grammar-statements format fcode format-string; } | grammar XG { inherit g; format html "{day}<sup>{day::oa}</sup> |{month:m} |{year}"; } scheme XS{ base gregorian; grammar XG; } writeln text.XS:html 2460127; | 1st July 2023 |
There are two aspects to the formatting of dates, firstly, interpreting the input from a user or application and secondly, creating the output to write a date in a particular way. If the text from the output can be fed directly back to the input, and the result remain unchanged, then the format is said to be reversible. The format statement is designed to handle both reversible and non-reversible text.
A format within a particular grammar is given a unique code by which it can be referred to. If a grammar inherits another, it may replace one of its inherited formats by reusing the same name.
If the format is being declared outside of a grammar statement, the code is a compound code including both the grammar and its name within that grammar, the parts separated by a colon ':' character.
Format Sub-Statement: rules
The conversion between date and text is controlled by the rules statement. Currently there are three rules available, as shown below.
| rules Statements | |
|---|---|
| Statement | Use |
| rules text | Use a text string to define the date. The default value. |
| rules units | Use value, unit pairs to define the date, or date elements. |
| rules iso8601 | Use the ISO 8601 standard that defines Gregorian dates. |
Format Sub-Statement: rules text
The text format rule uses a format string to control the order and style of the text being read or written. Since this is the default rule, there is no need to explicitly state it.
| Format Sub-Statements used with rules text | ||
|---|---|---|
| Statement | Example | Note |
| inout format-string; | inout "{day} |{month:m:a} |{year}"; | Format string used for both input and output. |
| input format-string; | input "{day} |{month} |{year}"; | Format string used for just input. |
| output format-string; | output "{day::os} |{month:m} |{year}"; | Format string used for just output. |
| separators string-expr; | separators "-"; | Characters to be used to separate date elements. Default is ":,". |
| rank string-list; | rank "ce", "ceyear", "month", "day"; | Set the significance order for input and output fields. |
| rankout string-list; | rankout year, nmonth, nmday, cday; | Set the significance order for output fields only. |
| visible switch; | visible yes; | Set the visibility for the format when listed. |
| pseudo:in string; | pseudo:in "Day Month Year"; | Set the string that shows the input format. |
| pseudo:out string; | pseudo:out "d-Mmm-yyyy"; | Set the string that shows the output format. |
| use:in string; | use:in calc_month; | Function code used to complete default fields. |
| padding string-list; | padding mon tue wed thur fri sat sun; | These words will be ignored if included. |
The format definition must contain either the
inout or,
one or both of the input and output sub-statements.
All these statements use the format-string to describe
how text is to be interpreted as a date
and/or how a date is to be output as text.
For input text, the format describes the expected order of the elements. The exact form of those elements (digits or text) is not normally important. If the number of elements is less than the format's, then the lest significant field or fields are removed from the format. A fields significance is determined by its ranking order. For example:-
| "{month} |{day} |{year}" |
In this example with a ranking of year, month, day
and 3 values input, the 1st value is assigned to the month field,
the 2nd to the day and 3rd to the year field.
If only 2 values are input, the 1st value is assigned to the month field
and the 2nd to the year field.
If only 1 value is input then it is assigned to the year field.
An element can be removed from from the ranking system by including a lexicon Name followed by an '*' asterisk. This means the lexicon name must be used and the element is positioned using the lexicon field name entry. It has the effect of making the element optional.
Elements which are not part of the ranking fields may be included as a non-ranking element, but the lexicon text (rather than a number) must be used so the field name can be determined.
The value inside the curly brackets describes the field to be output. The field name may be the default, or alias field name detailed in the associated grammar. Text outside of the curly brackets (excluding the '|' characters) is output verbatim. If an field is suppressed (a range short-cut for example), then everything in that element is omitted.
The table below shows the available styles.
| Field Format Specifier | |||
|---|---|---|---|
| Style | Syntax | Example | Result |
| Number | {Name} | {month} | 9 |
| Lexicon token | {Name:Lexicon} | {month:m} | September |
| Abbreviated lexicon | {Name:Lexicon:a} | {month:m:a} | Sep |
| Qualified Lexicon token | {Name:Lexicon::l} {Name:Lexicon::u} | {month:m::l} {month:m:a:u} | september SEP |
| Left padded number | {Name::lp:cwidth} | {month::lp:02} | 09 |
| Note, cwidth is the character used for padding followed by the minimum width. | |||
| Input Only Specifiers | |||
| Text value only. | {Name:Lexicon*} | {month:jg*} | |
| {Name:Lexicon*:a} | {month:jg*:a} | ||
| Note, Has the effect of making the element optional. | |||
| Output Only Specifiers | |||
| Number and ordinal suffix | {Name::os} {Name::os:u} | {month::os} {month::os:u} | 9th 9TH |
| Just ordinal suffix | {Name::oa} {Name::oa:u} | {month}_{month::oa} {month}_{month::oa:u} | 9_th 9_TH |
| Number, Roman numerals | {Name::rn} {Name::rn:l} | {month::rn} {month::rn:l} | IX ix |
Format Sub-Statement: separators
When inputting a date, by default the characters used to separate date elements are ',' and ';'. This sub-statement allows a change to the default.
Format Sub-Statement: rank
Rank is the order of the separate elements of a record that is used when an incomplete or range short-cut is used. The missing elements are assumed to be the lowest ranks, and the range covers all the possible dates.
If not given, the rank order is that stated by the grammar or the same as the default order.
Format Sub-Statement: rankout
The same as the rank sub-statement but it only affects the output of a format. It is used when separate input and output sub-statements are used.
Format Sub-Statement: visible
Set the visibility attribute for the Format to yes or no.
When a list of formats is requested, this format will only be included if the attribute is set to yes.
It is possible to override this by requesting a complete list of formats.
The default visibility is yes.
Format Sub-Statements: pseudo:in and pseudo:out
The pseudo date strings are those shown to indicate the format text expected. Normally these are automatically constructed using the format control string and alias pseudo grammar sub statement, or the pseudo lexicon sub-statement.
The pseudo:in and pseudo:out sub-statements can be used to override the automatically constructed ones.
Format Sub-Statement: use:in
Required when there are calculated fields included in the scheme.
The function name to be used to complete all the fields based on those fields used in the input text string. If not given the the function specified by the grammar sub-statement use from_text is used.
Format Sub-Statement: padding
The padding sub-statement allows words to be included in the formatted text which is then ignored when parsing it. The words will however act as a separator.
Note that when the format output style uses ordinal suffixes, the suffixes (th st nd rd) are automatically added to the padding list.
The case of the padding words is ignored.
Format Sub-Statement: rules units
A units format is one where a date (or parts of a date) is written as a sequence of value, unit pairs. Since the pair is self contained, they may be placed in any order.
By default, the unit names are the same as the field names. But if the alias unit grammar sub- statement has been used, these are the names that will be used.
A units format may is created automatically using the "u" format code. It can be used as follows.
| Example | Result |
|---|---|
| @date.g:u( "9month1948year19day" ) | 2432814 |
| @date.g:u( "2023y 4d 13m" ) | 2460314 |
| @scheme.g:u( "9 month" ) | {s:g null, 9, null, null} |
| @scheme.g:u( "2023y 9m 21d" ) | {s:g 2023, 9, 21, 4} |
| @text.g:u( 2460048 ) | "2023y 4m 13d" |
Note, this aspect of the language is still being developed. The units format has no options (at present) and is automatically created, using the "u" format code. Hence, there is no need to explicitly use it. It is included for completeness and future development only.
Format Sub-Statement: rules iso8601
Although it is possible to input and output dates conforming to the common parts of the ISO 8601 standard, full implementation requires its own format sub-system. This is achieved with the rules iso8601 sub-statement. This method can only be used with the Gregorian calendar schemes.
Various optional parts of the standard can be activated using a number of switches following the rules sub-statement. these can be broken down into a number of groups as follows.
| Switches used with rules iso8601 Sub-Statement | ||||
|---|---|---|---|---|
| Group | Switch | Description | Example | Output |
| Style | caldate | Dates are treated as Gregorian Year, Month and Day of month. Default | rules iso8601 caldate; | 1948-09-19 |
| week | Dates are output as Year, Week number and Day of week. | rules iso8601 week; | 1948-W38-7 | |
| ordinal | Dates are output as Year and Day of year. | rules iso8601 ordinal; | 1948-263 | |
| Extended | extended | Dates are output with '-' (hyphen) separators between the elements. Default | rules iso8601 extended; | 1948-09-19 |
| basic | Dates are output without any separators between the elements. | rules iso8601 basic; | 19480919 | |
| Expanded Year | year4 | Year is input and output as 4 positive digits without a leading '+'. Default | rules iso8601 year; | 1948-09-19 |
| year5 | Year are input and output as 5 digits with a leading '+' or '-'. | rules iso8601 year5; | +01948-09-19 | |
| year6 | Year are input and output as 6 digits with a leading '+' or '-'. | rules iso8601 year6; | +001948-09-19 | |
| Sign Prefix | nosign | Year is positive without a leading '+'. Default | rules iso8601 nosign; | 1948-09-19 |
| minus | Negative years have a leading '-'. | rules iso8601 minus; | 1948-09-19 | |
| sign | Year has a leading '+' or '-'. | rules iso8601 sign; | +1948-09-19 | |
| Date Set | dateset | Date is output as a Set of Ranges | rules iso8601 dateset; | [1948-09-19] |
The switches for each group may be mixed and matched as required. The order of the switches is not significant, except if rules are contradictory then the value to the right has precedence.
Examples of extending the formats of the library schemes.
| example/iso5.glcs Script |
|---|
| format g:iso_y5 { rules iso8601 caldate minus year5; } format g:iso_y5set { rules iso8601 dateset minus year5; } format gw:iso_y5wd { rules iso8601 week minus year5; } format go:iso_y5d { rules iso8601 ordinal minus year5; } |
| example/iso6.glcs Script |
|---|
| format g:iso_y6 { rules iso8601 caldate minus year6; } format g:iso_y6set { rules iso8601 dateset minus year6; } format gw:iso_y6wd { rules iso8601 week minus year6; } format go:iso_y6d { rules iso8601 ordinal minus year6; } |
